Light ROM 1/LIGHT-ROM 1 (Amiga Library Services)(1994).iso/ffdisks/d875.lha/ADoc/ADocEnglish.doc

Text File | 1993-02-27 | 25KB | 541 lines

AboutThisDoc

      This manual describes release 3.00 of the utility ADoc2. This program
  is (c)1990-1991-1992-1993 by Denis GOUNELLE, any commercial usage or  selling
  without author's written authorization is strictly forbidden.  You  can  copy
  and spread this program at the following conditions:

    - all the files must be provided
    - none of the file must have been modified
    - you don't charge more than $6 for copy fee

      "PowerPacker  2.3b"  is  (c)1989  by  PowerPeak  and  Nico  FRANCOIS,
  "PowerPacker Pro  3.0b"  is  (c)1990  by  PowerPeak  and  UGA  Software.  The
  "powerpacker.library"   library   is   (c)1990   by   Nico   FRANCOIS.    The
  "reqtools.library" library  ist  (c)1991-1992  by  Nico  FRANCOIS.  AREXX  is
  (c)1987 by William Hawes.

      In spite of several tests, no warranty is made that there's no errors
  in ADoc. YOU USE THIS PROGRAM AT YOUR OWN RISKS. In no event will I be liable
  for any damage, direct or indirect, resulting of the use of ADoc.

              >>> CLOSE THIS WINDOW TO CONTINUE <<<

Foreword

      ADoc2 is a new release of ADoc, fully rewritten in  order  to  remove
  some limitations and add several improvements.  Note    some  incompatibilities
  arose particularly at argument level. This program works  equally  under  1.3
  and 2.0 system releases.
      ADoc    is  an    utility  that  allows  you  to    manage    all  kinds   of
  documentations on any subject. It is able to    automatically  start  searching
  for a word selected by a mouse click, and to work  on  several  documentation
  files at the    same  time.  ADoc  can    also  use  straight  the  AutoDocs  and
  AmigaGuide files, as well as "PowerPacker" compressed files.

      You can send comments and criticism about this  program,  writing  at
  the following address :

                M. GOUNELLE Denis
                    Boîte 71
                   6, rue des cailloux
                  92110 CLICHY - FRANCE

      You can also send a message  to  the    following  Internet  address  :
  [e-mail]. Note that this mailbox is not mine, so please send only
  short messages. As I don't have direct access to the messages,  don't  expect
  an answer before a dozen of days.

      Thanks to Jean-Yves PROUX and Helmut J. ESENWEIN for    their  numerous
  suggestions, to Reza ELGHAZI for his help concerning AmigaGuide files, and to
  Simon HEWINSON who translated in English the "amiga.doc" file. Special thanks
  to Jean-Philippe RAPP for his ideas and his help concerning AutoDocs files.

Installation

      ADoc needs "reqtools.library" (version 2.0c or higher)  to  run.  You
  must copy this file in your "LIBS:" directory, if not yet done.
      ADoc is now localized, so  it  can  adapt  itself  to  your  favorite
  language. All you have to do is to  copy  the  good  catalog    file  into  the
  directory corresponding to  your  language.  For  exemple,  if  your    default
  language    is    french,    copy    the    "français.catalog"    into    the
  "SYS:Locale/Catalogs/Français" directory, under the name "adoc.catalog."

      The german catalog was translated by Stefan SALEWSKI.

HowDoesItWork

      ADoc works on documentation files, combined with a keyword (this  one
  is named "term" in this doc). Every doc file has an index file that allows to
  access the wanted terms nearly immediately. (Note : as a  result,  each  time
  you change a doc file, you'll have to rebuild its index file.) When  ADoc  is
  running, only is loaded in memory the index file. The name of this index file
  will be the doc file name plus an ".index" suffix.

      You can create your doc files with your favourite text editor;  these
  files consist of a series of definitions and each definition has a syntax  as
  follows :

          term
              text line 1
              text line 2

              etc...

              text line n

      At first, consider that the first two lines of a doc file have to  be
  empty (or in extreme circumstancies begin with a space or a  tab  character).
  The first character of each term must be at column 1 and the text lines  must
  begin with a space or a tab character. Empty lines are allowed.

                    CAUTION:

      The doc file format is not the same as in versions 3.xx and 4.xx.

      One term can't be more than 32 character long and can't  contain  any
  blanks or tabs :  valid  characters  are  upper  or  lower  letters,    digits,
  underline, and accented letters (ASCII codes between 217 and  246).  However,
  if needed, you can extend this character set (see below AdvancedConcepts).
      The term amount for each file as well as the    text  line  amount  for
  each term are unlimited (or rather, this limit is so  large  that  you'll  be
  short in memory long before).

      A text line can't be more than 256 characters. In order to bring  out
  some parts of your text, you can use the following ANSI sequences :

          ESC[1m  boldface on
          ESC[3m  italics on
          ESC[4m  underline on
          ESC[22m boldface off
          ESC[23m italics off
          ESC[24m underline off
          ESC[0m  normal character set

RunningADocfromCLI

  ADoc can be run from Workbench or from the CLI. By default, the doc  file  is
  "Amiga.doc", but, of course, in both cases, you can specify another filename.
  From the CLI, you can specify the following arguments :

  WBENCH
      Asks ADoc to use the Workbench screen. When this argument is missed  out,
      ADoc will open its own screen sized as the Workbench  screen.  On  error,
      when opening screen, ADoc will go automatically to the Workbench    screen.

  LACE
      Asks ADoc to use an interlaced screen. If you asked to use the  Workbench
      screen, and this one is not in interlaced mode,  this  argument  will  be
      ignored.

  FONT name
      Asks ADoc to use a given font rather than the default one. Name must take
      the form <FontName><SizeY>, for ex. "topaz8". ADoc is able to use any non
      proportional font so long as its size is 8 at least.
      If ADoc can't open the requested font, it will attempt to use the default
      one. If this font doesn't suit or ADoc can't open  it,  it  will  try  to
      access the topaz8 font. If it fails, ADoc will end immediately.

  MAKEIDX
      Tells ADoc the only operation to do is to create the index files.

  QUICK
      Asks ADoc not to display a text combined to the "AboutThisDoc" term, when
      starting. Usually, each  time  ADoc  opens  a  file,  it    looks  for  the
      "AboutThisDoc" term in this file, and then, if this one exists,  displays
      the corresponding text and waits for user  to  close  the  window  before
      continuing.

  AREXX
      Asks ADoc to go in AREXX mode. More information on how to use  ADoc  with
      AREXX in TheAREXXMode section below.

  ONEWINDOW
      Asks ADoc to open only one window at a time.

  NOCASE
      Asks ADoc not to differentiate lower and upper characters when processing
      files. This only will concern  files  whose  name  is  given  after  this
      option.

  NOSORT
      Asks ADoc not to sort the indexes of files whose name is specified  after
      this option.

  TABSIZE n
      Tells the tab size for the files    whose  name  is  specified  after  this
      option. Default size is 8.

  Any other argument will be considered as a doc file name to be used. You  can
  specify several files, by separating their names by spaces or commas (for ex.
  "ADoc file1 file2" or "ADoc file1,file2"). You can mix file names and options
  but let us remember that NOCASE, NOSORT, and    TABSIZE  options  only    concern
  files you specified after these options. ADoc will open these files  in  this
  given order. Unless you indicate one full path, firstly files will be  looked
  for in the current directory, then in the  "ADOC:"  one.  If  you  specify  a
  directory name instead of file name, ADoc will open all  the    files  in  this
  directory (apart from ".info" and ".index" files).

RunningADocFromWorkbench

  From Workbench, you can inwoke ADoc in several ways :

    - by  double-clicking  on  its  icon  (then  ADoc  will  use  the   default
      documentation file)
    - by double-clicking on one file icon having ADoc as  default  tool  (field
      "DEFAULT TOOL")
    - by clicking on icons of several files, holding down the  SHIFT  key,  and
      double-clicking on the ADoc icon.

  In all these cases, ADoc starts by looking into "TOOL  TYPES"  field  of  the
  program icon; this one may contain :

      FONT=name
      OPTIONS=[WBENCH][LACE][MAKEIDX][QUICK][AREXX][ONEWINDOW]

  For more information on these options, see  the  RunningADocfromCLI  section.
  Note option names must be separated by a "|" sign. After that, ADoc will open
  the doc files you specified; it will open them as it does from CLI except  it
  examines the "TOOL TYPES" field of each icon. This field may contain :

      TABSIZE=n
      OPTIONS=[NOCASE][NOSORT]

  For more information about these options, see the RunningADocfromCLI section.
  Note these three options only will concern  the  file  corresponding    to  the
  icon.

StartingADoc

      As I explained above, ADoc starts by opening some specified  file(s).
  At this time, ADoc attempts as well to open the index file  corresponding  to
  each doc file. If you didn't specified any file to open, ADoc  will  look  if
  the "ADocFile" variable is defined : if so, it's value  is  used  as  a  file
  name. Otherwise, the default    file  name  is    "Amiga.doc".  You  can  specify
  several file names is the "ADocFile" variable, just as from command line (for
  example: setenv ADocFile "exec.doc dos.doc").
      If ADoc can't find the index file, it will offer to create it. If you
  refuse, this doc file will not be usable but,  in  spite  of    it,  ADoc  will
  attempt opening other files.
      If ADoc detects a doc file was changed after an index was created, it
  will offer to update the index file. If you refuse, in spite of it,  the  doc
  file will be opened but later ADoc will be able to detect errors if the  file
  contents was changed. Note the date of index file creation is stored    in  the
  index file itself.

      Once all files are opened, ADoc will display a  requester;  this  one
  indicates the term list of first open file. We'll describe how  to  use  this
  requester in the TheTermRequester section.

TheTermRequester

      A term can be pointed out by a mouse click on it. Now  this  term  is
  displayed in a different colour. If you  click  a  second  time  on  it,  the
  requester  is  switched  off    and  ADoc  displays  in  a  window   the   text
  corresponding to that term.  I'll  describe  how  to  use  these  windows  in
  HowToManageWindows section.

      To choose a term, you can use the keyboard too. If you press any key,
  the key letter will  be  added  to  the  current  "prefix"  (displayed  in  a
  rectangle below the term list), and ADoc will display the list starting  from
  the first term that begins with this prefix. ADoc will complete  this  prefix
  as far as possible. If you press the    <BACKSPACE>  key  (above  the  <RETURN>
  key), the last prefix character will be deleted and the list will be    updated
  too. If you press the <RETURN> key, ADoc will display the text  corresponding
  to the  first  term  that  begins  with  this  prefix.  Note    ADoc  will  not
  differentiate upper and lower letters when  the  current  file  is  indicated
  after a NOCASE option.

      You can close the requester without selecting a term both by pressing
  the <ESC> key and by clicking in the close gadget either.  If  no  window  is
  open at this time, the program will abort.

      In fact, a term requester can allow you to select  from  among  three
  lists : the term list of the current file, the list of the opened  files  (if
  you have several opened files) and the list of terms that ADoc  found  during
  the previous search operation (provided a search was  made  before,  see  the
  Search section below).

      At the bottom, on the right corner of  term  requester,  you    have  a
  letter showing what a list is displayed : term list (T), file list (F),  list
  of found terms (S).
      To pass from a list to another, click the right mouse button, holding
  down one of the <SHIFT> keys. When the file list is displayed and you  select
  a file in this list, ADoc returns automatically to the term list and displays
  the list of terms in that file.

      When no window is open, the  term  requester    has  a    menu  with  the
  following options :

      Open window     see TheSpecialMenu below
      Search          see the Search section below
      Iconify          see the TheProjectMenu below
      Quit          this one allows to quit ADoc.

HowToManageWindows

      When    you  select  a    term,  ADoc  opens  a  window  to  display  the
  corresponding text. When a term is defined several times either in  a  single
  file or in several different files, all text lines will be joined in a  queue
  and displayed in one window. The window height is dependent on the amount  of
  lines ADoc must display. If there are too many lines,  only  the  first  page
  will be displayed and ADoc will add two  arrow  gadgets  (on  the  right  top
  corner) for scrolling this text.

      Of course, you can have several windows opened at the same  time.  In
  this case, the window which was activated when opening a new window is called
  the "parent window" of the new one.
      By default, these windows have standard  close,  dragging,  back  and
  front, and sizing gadgets. If you change the    size  of  a  window,  ADoc,  if
  needed, will add or remove automatically the arrow gadgets. Each  window  has
  three menus too : there are "Project",  "Tools"  and  "Special"  menus  (I'll
  describe  these  ones  in  TheProjectMenu,  TheToolsMenu  and  TheSpecialMenu
  sections, below). Finally, note ADoc recognize the following keys :

      HELP          list keys and their meaning
      ESC          close the current window
      UP          previous page
      DOWN          next page
      BACKSPACE      open parent window
      Shift-UP      previous term
      Shift-DOWN      next term

      When you click on a word, this one will be displayed in  a  different
  colour. If you click again on the same word, ADoc  will  automatically  start
  searching for the corresponding term in all open files. If this fails, screen
  flashes, otherwise a new window will be brought up.

TheProjectMenu

  Other term
      Bring up the term requester (see above TheTermRequester).

  Print
      Print the text contained in the active window. Note : the  possible  ANSI
      sequences will be correctly interpreted by the printer.

  Iconify
      Leave ADoc sleeping : if ADoc opened its own screen,  this  one  will  be
      closed, all the windows will be switched off and then ADoc  will    open  a
      small window on the left top corner in the  Workbench's  screen.  If  you
      click on the close gadget of this window, ADoc will ask you to confirm it
      before you abort. For "awaking" ADoc, activate this window and click  the
      right mouse button.
      Normally, ADoc keeps in memory all the text lines to be able switching on
      quickly all the windows when it would be awaken. The one drawback is that
      all possible memory will not be freed, so, when you ask ADoc  to    iconify
      itself, ADoc will ask you if you want to close all windows.  If  you  say
      yes, the memory will be completely freed and when ADoc will be awaken, it
      will bring up the term requester.

  Help...
      Displays some useful keys and their meaning (same as  pressing  the  HELP
      key)

  About...
      Display some infos about ADoc. Click inside this window or press a key to
      continue.

  Quit
      Allow to quit ADoc (asks you to confirm it).


TheToolsMenu

  Front Screen
      Allow to use ADoc in a already open screen (for ex. that one of your text
      editor). Only you need to move the screen -where you want switch on ADoc-
      in front of any screen, drag it down to unfold the screen where ADoc  is.
      Now, select this item : ADoc will close all the open windows  and  reopen
      these ones in the foreground screen.

                      CAUTION:

      Of course, you'll have a "Guru" if the screen  where  you  placed
      ADoc is closed before you quitted ADoc (or  placed  this  one  on
      another screen).

      Note this command will not work if you did not specify a font (see  above
      the RunningADocfromCLI section) and the font of your front screen doesn't
      suit.

  Close all
      Allow to close all the windows at the same time. After it  asked    you  to
      confirm, ADoc will close every window and display the term requester.

  Find
      Allow to start searching (see the Search section below).

  Information
      Display the account of avalaible files and terms, just as the account  of
      opened windows and displayed lines. To continue click on the "Ok" gadget.

TheSpecialMenu

  Open file
      Allow to open an additional doc file. A file requester is brought  up  so
      that you can specify what a file must be opened.

  Close file
      Allow to close the current file (i.e. the file where is defined the  term
      displayed in the active window). After it asked you to confirm, ADoc will
      close all the windows relied to this file and will close    it.  Note  this
      command will work only if at least two files are opened.

  One window
      If this option is selected, ADoc will open only one window at a time.

Search

      In the text lines, ADoc has the  capability  to  search  up  to  four
  strings simultaneously and display then the list of the  relied  terms.  When
  you select the "Search" item in the "Tools" menu, a  window  is  switched  on
  with four string gadgets. You have also an "CANCEL"  gadget,  to  abort  this
  operation, a "OK" gadget, to start your search, and an "Options" menu :

  low = UPP
      Ask ADoc not to differentiate upper and lower letters when searching.

  All strings
      Normally, ADoc is looking for all terms containing one of the strings you
      introduced. On the contrary, this item allows you  to  search  for  terms
      contaning ALL strings you specified.

  All files
      Ask ADoc to search in all open files, not only in the current file.

      When you start your search, a requester appears.  The  "Stop"  gadget
  allows you to break this search. As soon as the search finished, screen  will
  flash if no term was found. Otherwise, the term requester will be switched on
  and will display a list of found terms. That list  is  sorted,  and  kept  in
  memory until you stard a new search.

AdvancedConcepts

      The release 1.40 of ADoc introduced the concept of aliases, that is a
  manner to associate a same text to several terms, without  having  to  repeat
  the text several times. An alias definition follow the syntax:

      name1 alias name2

  The first character of "name2" must, as for any term definition, be at column
  one. There must be at least one space or tabulation between the three  words.
  The word "alias" must be in lower case  characters.  The  effect  of  such  a
  definition is that when the user will ask to get the "name1" term, ADoc  will
  automatically display the "name2" term instead. Aliases appear  in  the  term
  requester, and in the search function. You must be aware that there  is  *NO*
  recursivity check between aliases !
      An application of aliases could be the documentation    of  a  function
  library : often you will define several functions together. With the aliases,
  you can allow access to the definition by the name of each function, but  the
  text is defined only once.

      ADoc can combine automatically several  doc  files.  For  that,  it's
  enough to specify the name of file(s) to be combined, in the  first  line  of
  file which you want associate them with. If this line is empty or begins with
  a space or tab, its contents will be ignored. File names have to be separated
  by spaces or commas. You can indicate a directory name; in this case all  the
  files of that directory will be opened (except ".info" and ".index" files).

      To extend the character set you can use in a    term,  it's  enough  to
  specify additional characters in the second line of your doc    file.  If  this
  line is empty or begins with a space or tab, its contents  will  be  ignored.
  Otherwise, all characters of that line (up to first space, tab, slash or form
  feed) will be added to the default character set.  Note  this  character  set
  extension only will concern that file.

      ADoc    has  the  possibility    to   load   directly   any   compressed
  "PowerPacker" file, providing you have set up "powerpacker.library"  in  your
  LIBS: directory. It's not necessary (but recommended)  to  create  the  index
  file before you compress a doc file. ADoc will refuse to  load  an  encrypted
  file.
      After ADoc has  decompressed    a  file,  this    will  be  copied  in  a
  temporary file in the "T:" directory. So, using compressed  files  can  arise
  some memory problems, especially if you put T: directory in your  RAM:  disk.
  This temporary file will be deleted when you close it.

TheAREXXMode

      ADoc    always    opens  a  compatible  AREXX  port,  named  "ADoc_rexx".
  Messages on this port are waited for at the same time as  Intuition  messages
  on text windows, and can take the following forms :

      quit      quit ADoc
      request bring up the term requester
      fscreen ADoc moves all it's windows to the front screen
      tofront put ADoc screen in front of all screens
      toback  put ADoc screen in back of all screens
      ?term    start  searching  for  a  given  term,   and   display   the
          corresponding text if it is found
      @file   allows to open a other file while running ADoc

      The return code (RC variable) will be set  to  zero,  except  in  the
  following cases: bad request (return code 20), "?term" request and "term" not
  found (return code 5), "request" request and no term choosen (return code 5).
  Here is an example asking for help for the term "alias" :

      /* Ask for help for "alias" */
      ADDRESS "ADoc_rexx"
      "?alias"
      IF RC = 5 THEN SAY "not found !"

      Note quotes surrounding commands !
      If you launch ADoc with the option AREXX, the program operation  will
  be quite different : once ADoc opened the doc file(s), it will not switch  on
  the term requester but will display a message "Waiting for an AREXX  message"
  and will wait for messages on the AREXX port (or for  CTRL-C  to  abort  it).
  Moreover, when the last window will be  closed,  the    program  will  not  end
  itself but go back waiting for AREXX messages.

AutoDoc_files_support

      ADoc can recognize and use the AutoDocs files from Commodore. In most
  cases, no change are needed, but it is recommended to  verify  their    format:
  you must have at least two empty lines at  the  beginning,  followed    by  the
  table of contents and every term must start at column 1.
      In some cases, you won't find empty lines at the beginning, and terms
  will begin at column 2 and will be preceded by a "form feed" character  (i.e.
  CTRL-L). The program "AutoConvert", distributed with ADoc, will allow you  to
  convert those files into a correct format (Note : this program  can  only  be
  used from CLI). In all other cases, you'll have to  convert  these  files  by
  yourself.

AmigaGuide_files_support

      ADoc can now recognize AmigaGuide files, build their index files, and
  display their contents. The different syntaxes of the "@node"  directive  are
  handled :

      @node name
      @node "title"
      @node name "title"

  In the latter case, an "name" alias is automatically defined for the  "title"
  term. The "@title" directive is also handled.
      As ADoc doesn't handle spaces in term names,  they  are  replaced  by
  underscore characters. Links within text are displayed in boldface. As  names
  are truncated to 32 characters, some links may fail. Note that  ADoc    handles
  inter-files links, like:

             @{"foo" link help:general/bar}

  To allow such links, delimiters are automatically set to ":/." for AmigaGuide
  files.

TheADocMessages

      When an error  occurs,  ADoc    displays  in  a  small    window    a  name
  (usually, a filename) and an error code. This one is either an AmigaDOS error
  code or an internal code. In the first case, see your AmigaDOS Manual (or use
  the command "Fault") to have more information on this error code.
      There are the internal error codes :

      -1      empty file
      -2      read error
      -3      file is wrong (bad format, etc...)
      -4      file is compressed and there is no "powerpacker.library"
      -5      a problem occured while decrunching